<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Implementing Macros &mdash; creoleparser v0.6.x documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.6.x',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="creoleparser v0.6.x documentation" href="index.html" />
    <link rel="next" title="Changelog" href="changelog.html" />
    <link rel="prev" title="Basic Usage" href="usage.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="changelog.html" title="Changelog"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="usage.html" title="Basic Usage"
             accesskey="P">previous</a> |</li>
        <li><a href="contents.html">creoleparser v0.6.x documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="implementing-macros">
<span id="macros"></span><h1>Implementing Macros<a class="headerlink" href="#implementing-macros" title="Permalink to this headline">¶</a></h1>
<p>This page describes how to implement macros (i.e, extensions) in a wiki engine.
For end user usage, please see <a class="reference" href="syntax.html#syntax"><em>Syntax</em></a>.</p>
<div class="section" id="the-macro-func">
<h2>The <tt class="docutils literal"><span class="pre">macro_func</span></tt><a class="headerlink" href="#the-macro-func" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">macro_func</span></tt> is an optional argument used during instantiation of a dialect object.
Most often, this function will act as a dispatcher and call other functions based
on <tt class="docutils literal"><span class="pre">macro_name</span></tt>&#8216;s that are encountered while a Parser is working. Using this method,
the <tt class="docutils literal"><span class="pre">macro_func</span></tt> can be very simple, particularly if the actual macros have
compatible signatures.</p>
<p><strong>A simple macro_func:</strong></p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">creoleparser</span> <span class="k">import</span> <span class="n">parse_args</span>

<span class="k">def</span> <span class="nf">macro_dispatcher</span><span class="p">(</span><span class="n">macro_name</span><span class="p">,</span><span class="n">arg_string</span><span class="p">,</span><span class="n">body</span><span class="p">,</span><span class="n">isblock</span><span class="p">,</span><span class="n">environ</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">macro_name</span> <span class="ow">in</span> <span class="n">environ</span><span class="p">[</span><span class="s">&#39;macros&#39;</span><span class="p">]:</span>
       <span class="n">macro</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;name&#39;</span><span class="p">:</span> <span class="n">macro_name</span><span class="p">,</span>
                <span class="s">&#39;arg_string&#39;</span><span class="p">:</span> <span class="n">arg_string</span><span class="p">,</span>
                <span class="s">&#39;body&#39;</span><span class="p">:</span> <span class="n">body</span><span class="p">,</span>
                <span class="s">&#39;isblock&#39;</span><span class="p">:</span> <span class="n">isblock</span>
                <span class="p">}</span>
       <span class="n">pos</span><span class="p">,</span> <span class="n">kw</span> <span class="o">=</span> <span class="n">parse_args</span><span class="p">(</span><span class="n">arg_string</span><span class="p">)</span>
       <span class="k">return</span> <span class="n">environ</span><span class="p">[</span><span class="s">&#39;macros&#39;</span><span class="p">][</span><span class="n">macro_name</span><span class="p">](</span><span class="n">macro</span><span class="p">,</span> <span class="n">environ</span><span class="p">,</span> <span class="o">*</span><span class="n">pos</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
</pre></div>
</div>
<p>In the code above, <tt class="docutils literal"><span class="pre">eniviron['macros']</span></tt> is a dictionary of functions. Note that if <tt class="docutils literal"><span class="pre">macro_name</span></tt> is
not in the dictionary, or if a macro returns <cite>None</cite>, creoleparser will treat the macro as
unknown and render the raw wikitext unaltered.</p>
<p>Additional information about <tt class="docutils literal"><span class="pre">macro_func</span></tt> is documented with the <a title="creoleparser.dialects.create_dialect" class="reference" href="modules/dialects.html#creoleparser.dialects.create_dialect"><tt class="xref docutils literal"><span class="pre">create_dialect()</span></tt></a> factory function.</p>
</div>
<div class="section" id="macros-returning-html">
<h2>Macros Returning HTML<a class="headerlink" href="#macros-returning-html" title="Permalink to this headline">¶</a></h2>
<p>In order for a macro to return raw HTML, the HTML must be wrapped in a genshi.Markup object. See
an example <a class="reference" href="http://creoleparserwiki.appspot.com/pages/HTMLMacroExample">here</a></p>
</div>
<div class="section" id="macros-returning-creole">
<h2>Macros Returning Creole<a class="headerlink" href="#macros-returning-creole" title="Permalink to this headline">¶</a></h2>
<p>Don&#8217;t forget that macros can return simple strings (preferably as unicode objects) rather than
genshi objects. These will be processed as Creole markup (potentially including other macros!)
in their new context.</p>
</div>
<div class="section" id="how-can-i-stop-a-macro-from-being-placed-in-a-paragraph-or-visa-versa">
<h2>How can I stop a macro from being placed in a paragraph? (or visa versa)<a class="headerlink" href="#how-can-i-stop-a-macro-from-being-placed-in-a-paragraph-or-visa-versa" title="Permalink to this headline">¶</a></h2>
<p>Creoleparser tries not to use paragraphs if the content they would enclose are
valid children of the <cite>body</cite> element (according to  xhtml1 strict). For example, if a section of
wiki text is enclosed entirely in a regular bodied macro, and that macro outputs an Element with a <cite>div</cite> tag, no
<cite>p</cite> tag will be added.</p>
<p>For <em>block</em> type macros (i.e., when <tt class="docutils literal"><span class="pre">isblock</span></tt> is true), creole parser will <em>add</em> a <cite>p</cite> tag
if the macro&#8217;s return value indicates it isn&#8217;t a valid child of the <cite>body</cite> element.</p>
<div class="section" id="guidelines-for-macro-return-values-and-paragraph-control">
<h3>Guidelines for macro return values and paragraph control<a class="headerlink" href="#guidelines-for-macro-return-values-and-paragraph-control" title="Permalink to this headline">¶</a></h3>
<ul>
<li><p class="first">Return a Fragment to <strong>always</strong> apply a <cite>p</cite> tag (unless the macro appears in other block level markup) e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">return</span> <span class="n">genshi</span><span class="o">.</span><span class="n">builder</span><span class="o">.</span><span class="n">tag</span><span class="p">(</span><span class="n">my_output</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p class="first">Return a Stream (using the generate method) or Markup object to <strong>never</strong> apply a <cite>p</cite> tag, e.g.:</p>
<div class="highlight-python"><pre>return genshi.builder.tag(my_output).generate()
or
return genshi.Markup('&lt;div&gt;...&lt;/div&gt;')</pre>
</div>
</li>
<li><p class="first">Return a string or Element to let creoleparser decide, e.g.:</p>
<div class="highlight-python"><pre>return 'some string (raw html will be escaped!)'
or
return genshi.builder.tag.div(my_output)</pre>
</div>
</li>
</ul>
<p>Generally, returning a string or Element will reliably produce valid xhtml.
When returning other objects, you should follow the rules above.</p>
</div>
</div>
<div class="section" id="other-macro-implementation-examples">
<h2>Other Macro Implementation Examples<a class="headerlink" href="#other-macro-implementation-examples" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><a class="reference" href="http://code.google.com/p/creoleparser/source/browse/trunk/creoleparser/test_cheat_sheet_plus.py">test_cheat_sheet_plus.py</a>
which is used to generate the <a class="reference" href="http://creoleparser.googlepages.com/CheatSheetPlus.html">creoleparser cheatsheet</a> and
help validate any changes made to the library code.</li>
<li><a class="reference" href="http://code.google.com/p/urlminer/source/browse/examples/wiki/macros.py">the code used in the sandbox wiki</a>.</li>
</ul>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="contents.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference" href="">Implementing Macros</a><ul>
<li><a class="reference" href="#the-macro-func">The <tt class="docutils literal"><span class="pre">macro_func</span></tt></a></li>
<li><a class="reference" href="#macros-returning-html">Macros Returning HTML</a></li>
<li><a class="reference" href="#macros-returning-creole">Macros Returning Creole</a></li>
<li><a class="reference" href="#how-can-i-stop-a-macro-from-being-placed-in-a-paragraph-or-visa-versa">How can I stop a macro from being placed in a paragraph? (or visa versa)</a><ul>
<li><a class="reference" href="#guidelines-for-macro-return-values-and-paragraph-control">Guidelines for macro return values and paragraph control</a></li>
</ul>
</li>
<li><a class="reference" href="#other-macro-implementation-examples">Other Macro Implementation Examples</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="usage.html"
                                  title="previous chapter">Basic Usage</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="changelog.html"
                                  title="next chapter">Changelog</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/macros.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="changelog.html" title="Changelog"
             >next</a> |</li>
        <li class="right" >
          <a href="usage.html" title="Basic Usage"
             >previous</a> |</li>
        <li><a href="contents.html">creoleparser v0.6.x documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2009, Stephen Day.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.1.
    </div>
<script type="text/javascript">var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));</script><script type="text/javascript">try {var pageTracker = _gat._getTracker("UA-2934490-7");pageTracker._trackPageview();} catch(err) {}</script>  </body>
</html>